---
description: "Reference for Nitric's v0 Node.js library - Create APIs with the Nitric Node.js SDK"
---

# Node.js - api()

Creates a new HTTP API.

```javascript
import { api } from '@nitric/sdk'

const publicApi = api('public')
```

## Parameters

<Properties>
  <Property name="name" required type="string">
    The unique name of this API within the app. Subsequent calls to `api` with
    the same name will return the same object.
  </Property>
  <Property name="options" type="object">
    Additional options when creating the API.
    <Properties nested>
      <Property name="path" type="string">
        Base path for all routes in the API.
      </Property>
      <Property name="middleware" type="HttpMiddleware or HttpMiddleware[]">
        Middleware to apply to all routes and methods of the API.
      </Property>
      <Property
        name="securityDefinitions"
        type="map<string, SecurityDefinition>"
      >
        Security definitions defined by this API.
      </Property>
      <Property name="security" type="map<string, string[]>">
        Security rules to apply with scopes to the entire API. Keys must match a
        **securityDefinition**.
      </Property>
    </Properties>
  </Property>
</Properties>

### SecurityDefinition Parameters

<Properties>
  <Property name="kind" required type="string">
    value must be <code>jwt</code>
  </Property>
  <Property name="issuer" required type="string">
    the issuer for the JWT tokens e.g.{' '}
    <code>https://account.region.auth0.com</code>
  </Property>
  <Property name="audiences" required type="string[]">
    the <code>aud</code> that will be applied to JWT tokens from the issuer.
  </Property>
</Properties>

### Notes

The `middleware` property on the `options` param is useful for applying universal middleware such as CORS headers or Auth, across an entire API from a single place.

## Examples

### Create an API

```javascript
import { api } from '@nitric/sdk'

const publicApi = api('public')
```

### Create an API with universal middleware

```javascript
import { api } from '@nitric/sdk'
import { authMiddleware } from '../middleware'

const privateApi = api('private', { middleware: authMiddleware })
```

### Define middleware

```javascript
const authMiddleware = async (ctx, next) => {
  // Perform auth validation.
  return await next(ctx)
}
```

### Notes

Middleware services are supplied an `HttpContext` object and a `next()` function which calls the next middleware in the chain.

### Create an API with a base path

If you need to put all the routes in your api below a shared base path, you can do that with the `path` option. In this example we ensure all routes start with `/api/v1/` before the route specific path.

```javascript
import { api } from '@nitric/sdk'

const apiV1 = api('private', { path: '/api/v1' })
```

### Apply JWT authentication to an API

```javascript
import { api, jwt } from '@nitric/sdk'

const secureApi = api('secure', {
  // security requirements for your API are defined here
  securityDefinitions: {
    // define a security definition called 'user'
    user: jwt({
      issuer: 'https://example-issuer.com',
      audiences: ['YOUR-AUDIENCES'],
    }),
  },
  // You can optionally apply security rules to the entire API
  security: {
    // apply the 'user security definition the whole API'
    user: [
      // Optionally apply required scopes to this api
      // in this case users will require the products:read scope to access the API
      'products:read',
    ],
  },
})
```
